Skip to main content

Import Clusters via Token

The Import via Token feature allows you to bring your existing Kubernetes clusters under Atmosly management quickly — without requiring full cloud account integration. This enables you to monitor and scan clusters hosted on any provider using only a token and an API endpoint.

Introduction​

Importing clusters via token provides a simple, flexible alternative to cloud account integration. This approach is ideal if:

  • You need to manage clusters without granting full cloud access.
  • You want to connect self-hosted, on-premise, or restricted environments.
  • You prefer token-based authentication for security or compliance.
  • Your cluster runs on a provider other than AWS or GCP.

Note: This method offers limited functionality compared to full cloud integration (e.g., no cost analysis, limited automation).

Key Benefits​

  • Fast Onboarding: Import clusters in minutes using token credentials.
  • Broad Compatibility: Works with any Kubernetes cluster that supports API access via token.
  • Security Insights: Run Kubescape security scans and monitor workloads without deeper cloud account integration.
  • Minimal Permissions Required: No need to share full cloud credentials.
  1. From the main navigation menu, click Clusters.
  2. Click the Add Cluster or Import Cluster button.
  3. From the cloud provider dropdown, choose Import via Token.

Providing Your Cluster Details​

Once you've selected Import via Token, fill out the required fields:

1. Authentication Token​

What it is: A Kubernetes API authentication token (service account token) with sufficient permissions to access cluster metadata and workloads.

Where to get it:

  • Click the link Download script for fetching token and endpoint provided in the import form.
  • Run the script in your cluster environment to retrieve the token securely.
  • The token must have cluster-admin or equivalent permissions.

2. Endpoint​

What it is: The Kubernetes API server endpoint URL (must include https:// prefix).

Where to get it:

  • The same script you downloaded provides this value.
  • Alternatively, run kubectl config view or check your cloud provider's dashboard.

3. Skip TLS Verify (Optional)​

What it is: A toggle to skip TLS certificate verification when connecting to the cluster API server.

When to use:

  • Enable this if your cluster uses a self-signed certificate.
  • For production clusters, it is recommended to keep this disabled for security.

4. Cluster Type​

Select how the cluster API is accessible:

TypeDescription
PUBLICCluster API endpoint is publicly accessible
PRIVATECluster API endpoint is only accessible from within the network (requires ops-agent)

For PRIVATE clusters, Atmosly will generate an ops-agent installation command. Run this command inside your cluster to establish a secure connection.

note

The ops-agent installation command includes a temporary security token that expires in 24 hours. Regenerate if installation is delayed.

Capabilities After Import​

When you import via token, you will be able to:

  • View Nodes: Monitor node health and configurations
  • View Pods: Track pod status and workloads
  • Run Security Scan: Evaluate vulnerabilities and compliance using Kubescape
  • View Workloads: Monitor deployments, statefulsets, jobs, and other Kubernetes resources
  • Manage RBAC: Configure role-based access control for the cluster

Limitations:

  • Cost Analysis Not Available: You cannot see spending, cost breakdowns, or forecasts
  • No Cloud-specific Automation: Features tied to cloud APIs (node group management, cloud-native add-ons) are not available
  • No Add-on Auto-install: Add-ons are not automatically deployed on token-imported clusters

Running a Security Scan​

After import, you can run security scans:

  1. Navigate to Cluster Details.
  2. Click Cluster Actions dropdown (top-right).
  3. Select Run Security Scan.
  4. Review security and compliance results in the dashboard.

Troubleshooting​

Token Expired or Invalid

  • Re-run the fetch script and update the token.
  • Ensure the token has cluster-admin or equivalent permissions.

Invalid Endpoint

  • Confirm the URL includes https:// and is reachable from the platform.
  • For private clusters, ensure the ops-agent is installed and running.

Connection Failed

  • If using Skip TLS Verify: false, ensure your cluster's CA certificate is valid and not expired.
  • For private clusters, verify the ops-agent pod is running: kubectl get pods -n atmosly-system

Tips for Successful Imports​

  • Use short-lived tokens to reduce security risk.
  • Run regular security scans to maintain compliance.
  • For private clusters, ensure the ops-agent has outbound connectivity to Atmosly.
  • If you need full capabilities (cost tracking, node group management, cloud-native add-ons), consider full cloud account integration.

FAQ​

Q: Can I import clusters from any provider? A: Yes — any Kubernetes cluster accessible via API token and endpoint, including on-premise, self-hosted, and multi-cloud setups.

Q: How often does the platform sync imported cluster data? A: Cluster status and workloads are refreshed periodically in near real-time.

Q: Can I convert an imported cluster to a fully integrated cloud account later? A: Yes — delete the imported cluster and re-import using your cloud account credentials via the Bring Your Cluster flow.